Pular para o conteúdo principal

Troubleshooting

Esta seção descreve os principais problemas relacionados ao Cash-out, suas possíveis causas e formas de resolução.

A API processa as transações em duas etapas:

  1. Erros Síncronos: Problemas identificados de forma imediata durante a validação inicial da requisição.
  2. Erros Assíncronos: Problemas identificados durante o fluxo de processamento, após o aceite inicial da requisição. Estes são notificados através de Webhooks.

1. Erros Síncronos

Os erros síncronos ocorrem no exato momento do envio da requisição HTTP para a API. Caso alguma validação falhe (ex: campos obrigatórios ausentes, formatação inválida ou problemas de autenticação), a API retorna imediatamente um código HTTP (como 400 Bad Request ou 401 Unauthorized), contendo o detalhamento na resposta principal.

Causas Síncronas Comuns:​

  • Cabeçalhos ou campos bloqueadores faltando no formato do JSON.
  • Chave Pix inválida ou dados bancários inconsistentes.
  • Estrutura da payload incompatível com a especificação da API.

Exemplo de Payload de Erro Síncrono​

Quando ocorre um erro síncrono, a nossa API retorna uma estrutura JSON padronizada. Abaixo temos um exemplo comum de retorno 422 Unprocessable Entity:

{
    "title": "Please refer to the errors property for additional details.",
    "status": 422,
    "code": "START_PAYMENT_NOT_FOUND",
    "errors": [
        "Não foi encontrado uma inicialização de pagamento com este ID."
    ]
}
  • code: Um breve resumo ou identificador sobre do que se trata o erro.
  • errors: Uma matriz (array) contendo uma curta descrição dos detalhes e motivos das validações que falharam.
Erros pouco claros?

Em casos isolados onde a mensagem de erro retornada no corpo da resposta não estiver muito clara ou descritiva, nós recomendamos que você verifique os Headers (cabeçalhos) enviados na sua requisição original.

Muitas vezes, a omissão ou formatação inválida de cabeçalhos fundamentais como idempotencyKey, x-delfinance-account-id e afins provocam este bloqueio imediato na entrada da API.

Solução:​

Consulte a documentação técnica para o endpoint específico, atente-se aos campos obrigatórios e valide suas chaves de API. Caso o erro persista, avalie os campos code e errors devolvidos na própria resposta HTTP.

2. Erros Assíncronos (Webhooks)

Os erros assíncronos ocorrem depois que a API recebe e processa a requisição inicial com sucesso (retornando, por exemplo, o código HTTP 202 Accepted), movendo a transação para uma fila de processamento. Caso um erro fatal ocorra na etapa de execução, um evento via Webhook será despachado para a sua aplicação.

Para erros durante o Cash-out, você receberá um evento do tipo PIX_PAYMENT_ERROR com status PIX_ERROR. Dê atenção redobrada ao campo error.code contido no Payload.

Abaixo listamos os erros assíncronos mais conhecidos:

2.1. DEL01: Saldo Insuficiente​

Exemplo do Webhook​

{
    "amount": 100.00,
    "eventType": "PIX_PAYMENT_ERROR",
    "status": "PIX_ERROR",
    "error": {
        "code": "DEL01",
        "description": "Saldo insuficiente."
    },
    "correlationId": null,
    "createdAt": "2023-10-27T10:00:00Z",
    "description": "Payment to supplier",
    "idempotencyKey": "a1b2c3d4-e5f6-7890-1234-56789abcdef0",
    "endToEndId": "E12345678202310271000abcdefghij",
    "finishedAt": "2023-10-27T10:00:05Z",
    "beneficiary": { ... },
    "payer": { ... }
}

Causa​

A conta de origem (Cash-out) não possui saldo disponível o bastante para cobrir o valor transferido.

Solução​

Verifique o saldo da conta Delfinance. Se necessário, reabasteça a conta (Cash-in) e, então, tente iniciar uma nova transferência.

2.2. DEL02: Limite Insuficiente​

Exemplo do Webhook​

{
    "amount": 5000.00,
    "eventType": "PIX_PAYMENT_ERROR",
    "status": "PIX_ERROR",
    "error": {
        "code": "DEL02",
        "description": "Limite insuficiente."
    },
    "correlationId": null,
    "createdAt": "2023-10-27T10:00:00Z",
    "description": "Payment to supplier",
    "idempotencyKey": "a1b2c3d4-e5f6-7890-1234-56789abcdef0",
    "endToEndId": "E12345678202310271000abcdefghij",
    "finishedAt": "2023-10-27T10:00:05Z",
    "beneficiary": { ... },
    "payer": { ... }
}

Causa​

O montante transferido excede os Limites de Uso operacionais vigentes para sua conta (limite máximo estabelecido para uma transação unitária, ou o somatório do período diurno/noturno).

Solução​

Acompanhe os Limites de Uso vinculados à conta. Quando cabível, solicite o aumento do valor do limite pelo endpoint respectivo da API ou painel de controle. Com a aprovação ativa, efetue nova tentativa de envio.

2.3. DEL03: Bloqueio por Regras de Segurança​

Exemplo do Webhook​

{
    "amount": 1500.00,
    "eventType": "PIX_PAYMENT_ERROR",
    "status": "PIX_ERROR",
    "error": {
        "code": "DEL03",
        "description": "Transferência bloqueada devido a critérios de segurança."
    },
    "correlationId": null,
    "createdAt": "2023-10-27T10:00:00Z",
    "description": "Payment to supplier",
    "idempotencyKey": "a1b2c3d4-e5f6-7890-1234-56789abcdef0",
    "endToEndId": "E12345678202310271000abcdefghij",
    "finishedAt": "2023-10-27T10:00:05Z",
    "beneficiary": { ... },
    "payer": { ... }
}

Causa​

A transação foi interrompida devido a critérios internos de segurança.

Solução​

Se acreditar que trata-se de um bloqueio indevido, contate o time de suporte da Delfinance fornecendo os IDs necessários (como endToEndId e idempotencyKey) e as informações para averiguação.

Erros de Limite​

Os erros relacionados a limites de uso são retornados seguindo uma nomenclatura padrão, que ajuda a identificar o serviço e o tipo de limite que foi excedido. O formato do código de erro é:

UL + [Acrônimo do Serviço] + [Código do Limite]

Acrônimos de Serviço​

  • PIX: Pix
  • TED: Transferência Externa (TED)
  • TFI: Transferência Interna
  • BIL: Pagamento

Códigos de Limite​

  • 001: Diário
  • 002: Mensal
  • 003: Noturno
  • 004: Por Transação
  • 005: Por Transação noturna

Exemplos:

  • ULPIX001: Limite Diário do serviço Pix excedido.
  • ULTED004: Limite Por Transação do serviço TED excedido.

Informação Útil para Suporte​

Para registrar um ticket de suporte acerca de um erro na API de Cash-out, lembre-se de fornecer:

  • O campo endToEndId obtido (se houver)
  • A idempotencyKey do processamento
  • Data/horário em que a tentativa ocorreu
  • O ID da conta vinculada (delfinance-account-id)
  • Os retornos e os logs de Payload ou corpo do Webhook recebido

Anexo: Erros Diretos do SPI​

Além dos mapeamentos específicos da Delfinance, transações podem ser canceladas diretamente pelo Sistema de Pagamentos Instantâneos (SPI) do Banco Central ou pelo participante recebedor. Quando isso ocorre, o Webhook repassa o código de erro genérico retornado pelo SPI, permitindo identificar o motivo exato da falha.

Os erros de SPI mais comuns incluem:

CódigoDescrição
AC03Número da conta do recebedor inexistente ou inválido.
AB03Liquidação da transação interrompida devido a timeout no SPI.
AC06Conta transacional do usuário recebedor encontra-se bloqueada.
AC07Número da conta transacional do usuário recebedor encerrada.
AC14Tipo incorreto para a conta transacional do usuário recebedor.
DS04PIX rejeitado pelo participante do recebedor.
AG03Tipo de transação não é suportado/autorizado na conta do recebedor. Exemplo: transferência para conta salário.
ED05Erro no processamento do pagamento instantâneo (erro genérico).
AM02Ordem de pagamento/devolução em valor que faz superar o limite permitido para o tipo de conta transacional creditada.
JDPISPI015Falha na validação de limite transacional (bloqueio de segurança da parceira aplicado a limite por transação para Pessoa Física e Jurídica).